SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/SelfLoader.Z/SelfLoader

Text File | 1998-10-28 | 12.2 KB | 265 lines

     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))



     NNNNAAAAMMMMEEEE
      SelfLoader - load functions only on demand

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          package FOOBAR;
          use SelfLoader;

          ... (initializing    code)

          __DATA__
          sub {....


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      This module tells its    users that functions in    the FOOBAR
      package are to be autoloaded from after the __DATA__ token.
      See also the section on _A_u_t_o_l_o_a_d_i_n_g in the _p_e_r_l_s_u_b manpage.

      TTTThhhheeee ________DDDDAAAATTTTAAAA________ ttttooookkkkeeeennnn

      The __DATA__ token tells the perl compiler that the perl
      code for compilation is finished. Everything after the
      __DATA__ token is available for reading via the filehandle
      FOOBAR::DATA,    where FOOBAR is    the name of the    current
      package when the __DATA__ token is reached. This works just
      the same as __END__ does in package 'main', but for other
      modules data after __END__ is    not automatically retreivable
      , whereas data after __DATA__    is.  The __DATA__ token    is not
      recognized in    versions of perl prior to 5.001m.

      Note that it is possible to have __DATA__ tokens in the same
      package in multiple files, and that the last __DATA__    token
      in a given package that is encountered by the    compiler is
      the one accessible by    the filehandle.    This also applies to
      __END__ and main, i.e. if the    'main' program has an __END__,
      but a    module 'require'd (_not_ 'use'd) by that program has a
      'package main;' declaration followed by an '__DATA__', then
      the DATA filehandle is set to    access the data    after the
      __DATA__ in the module, _not_    the data after the __END__
      token    in the 'main' program, since the compiler encounters
      the 'require'd file later.

      SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr aaaauuuuttttoooollllooooaaaaddddiiiinnnngggg

      The SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr works by the user placing the __DATA__    token
      _a_f_t_e_r    perl code which    needs to be compiled and run at
      'require' time, but _b_e_f_o_r_e subroutine    declarations that can
      be loaded in later - usually because they may    never be
      called.

      The SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr will read from    the FOOBAR::DATA filehandle to
      load in the data after __DATA__, and load in any subroutine



     Page 1                        (printed 10/23/98)






     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))



      when it is called. The costs are the one-time    parsing    of the
      data after __DATA__, and a load delay    for the    _first_    call
      of any autoloaded function. The benefits (hopefully) are a
      speeded up compilation phase,    with no    need to    load functions
      which    are never used.

      The SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr will stop reading from    __DATA__ if it
      encounters the __END__ token - just as you would expect.  If
      the __END__ token is present,    and is followed    by the token
      DATA,    then the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr leaves the FOOBAR::DATA filehandle
      open on the line after that token.

      The SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr exports the AUTOLOAD subroutine to the
      package using    the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr,    and this loads the called
      subroutine when it is    first called.

      There    is no advantage    to putting subroutines which will
      _always_ be called after the __DATA__    token.

      AAAAuuuuttttoooollllooooaaaaddddiiiinnnngggg aaaannnndddd ppppaaaacccckkkkaaaaggggeeee lllleeeexxxxiiiiccccaaaallllssss

      A 'my    $pack_lexical' statement makes the variable
      $pack_lexical    local _only_ to    the file up to the __DATA__
      token. Subroutines declared elsewhere    _cannot_ see these
      types    of variables, just as if you declared subroutines in
      the package but in another file, they    cannot see these
      variables.

      So specifically, autoloaded functions    cannot see package
      lexicals (this applies to both the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr    and the
      Autoloader).    The vars pragma    provides an alternative    to
      defining package-level globals that will be visible to
      autoloaded routines. See the documentation on    vvvvaaaarrrrssss in    the
      pragma section of the    _p_e_r_l_m_o_d    manpage.

      SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr aaaannnndddd AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr

      The SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr can replace the AutoLoader - just change 'use
      AutoLoader' to 'use SelfLoader' (though note that the
      SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr exports the AUTOLOAD function - but if you    have
      your own AUTOLOAD and    are using the AutoLoader too, you
      probably know    what you're doing), and    the __END__ token to
      __DATA__. You    will need perl version 5.001m or later to use
      this (version    5.001 with all patches up to patch m).

      There    is no need to inherit from the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr.

      The SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr works similarly to the    AutoLoader, but    picks
      up the subs from after the __DATA__ instead of in the
      'lib/auto' directory.     There is a maintainance gain in not
      needing to run AutoSplit on the module at installation, and
      a runtime gain in not    needing    to keep    opening    and closing



     Page 2                        (printed 10/23/98)






     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))



      files    to load    subs. There is a runtime loss in needing to
      parse    the code after the __DATA__. Details of    the AAAAuuuuttttooooLLLLooooaaaaddddeeeerrrr
      and another view of these distinctions can be    found in that
      module's documentation.

      ________DDDDAAAATTTTAAAA________,,,, ________EEEENNNNDDDD________,,,, aaaannnndddd tttthhhheeee FFFFOOOOOOOOBBBBAAAARRRR::::::::DDDDAAAATTTTAAAA ffffiiiilllleeeehhhhaaaannnnddddlllleeee....

      This section is only relevant    if you want to use the
      FOOBAR::DATA together    with the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr.

      Data after the __DATA__ token    in a module is read using the
      FOOBAR::DATA filehandle. __END__ can still be    used to    denote
      the end of the __DATA__ section if followed by the token
      DATA - this is supported by the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr. The FOOBAR::DATA
      filehandle is    left open if an    __END__    followed by a DATA is
      found, with the filehandle positioned    at the start of    the
      line after the __END__ token.    If no __END__ token is
      present, or an __END__ token with no DATA token on the same
      line,    then the filehandle is closed.

      The SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr reads from wherever the current position of
      the FOOBAR::DATA filehandle is, until    the EOF    or __END__.
      This means that if you want to use that filehandle (and ONLY
      if you want to), you should either

      1. Put all your subroutine declarations immediately after
      the __DATA__ token and put your own data after those
      declarations,    using the __END__ token    to mark    the end    of
      subroutine declarations. You must also ensure    that the
      SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr reads first by  calling 'SelfLoader-
      >_l_o_a_d__s_t_u_b_s();', or by using a function which    is selfloaded;

      or

      2. You should    read the FOOBAR::DATA filehandle first,
      leaving the handle open and positioned at the    first line of
      subroutine declarations.

      You could conceivably    do both.

      CCCCllllaaaasssssssseeeessss aaaannnndddd iiiinnnnhhhheeeerrrriiiitttteeeedddd    mmmmeeeetttthhhhooooddddssss....

      For modules which are    not classes, this section is not
      relevant.  This section is only relevant if you have methods
      which    could be inherited.

      A subroutine stub (or    forward    declaration) looks like

        sub    stub;

      i.e. it is a subroutine declaration without the body of the
      subroutine. For modules which    are not    classes, there is no



     Page 3                        (printed 10/23/98)






     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr((((3333))))



      real need for    stubs as far as    autoloading is concerned.

      For modules which ARE    classes, and need to handle inherited
      methods, stubs are needed to ensure that the method
      inheritance mechanism    works properly.    You can    load the stubs
      into the module at 'require' time, by    adding the statement
      'SelfLoader->_l_o_a_d__s_t_u_b_s();' to the module to do this.

      The alternative is to    put the    stubs in before    the __DATA__
      token    BEFORE releasing the module, and for this purpose the
      Devel::SelfStubber module is available.  However this    does
      require the extra step of ensuring that the stubs are    in the
      module. If this is done I strongly recommend that this is
      done BEFORE releasing    the module - it    should NOT be done at
      install time in general.

     MMMMuuuullllttttiiiipppplllleeee ppppaaaacccckkkkaaaaggggeeeessss aaaannnndddd ffffuuuullllllllyyyy qqqquuuuaaaalllliiiiffffiiiieeeedddd ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee nnnnaaaammmmeeeessss
      Subroutines in multiple packages within the same file    are
      supported - but you should note that this requires exporting
      the SelfLoader::AUTOLOAD to every package which requires it.
      This is done automatically by    the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr when it first
      loads    the subs into the cache, but you should    really specify
      it in    the initialization before the __DATA__ by putting a
      'use SelfLoader' statement in    each package.

      Fully    qualified subroutine names are also supported. For
      example,

         __DATA__
         sub foo::bar {23}
         package baz;
         sub dob {32}

      will all be loaded correctly by the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr, and the
      SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr will ensure that the packages 'foo' and 'baz'
      correctly have the SSSSeeeellllffffLLLLooooaaaaddddeeeerrrr    AUTOLOAD method    when the data
      after    __DATA__ is first parsed.


















     Page 4                        (printed 10/23/98)